ProDOS File Navigator can execute BIN files (type $06) and NCF files (type $66), which are functionally equivalent to BIN files. While the code in either type of file is running, it has access to all of PFN's routines, data tables, strings, and buffers; in other words, the file is running in the very underbelly of PFN itself.

If you want to write assembly language programs with ProDOS File Navigator in mind, you will need an understanding of how it uses memory, how it calls your program, how it stores its data, and how you can call some of its routines.

ProDOS File Navigator will load your BIN or NCF file at the memory location indicated by its auxiliary type. If this happens to be a memory area used by PFN itself, your program will not load and will not execute. It transfers control to your program with a JSR instruction. At this point, the screen is exactly as it was when the user pressed E or Return, and the text window is set to just between the two lines of hyphens.

An RTS in your program will return control to ProDOS File Navigator; control will return at the point where PFN draws everything on the screen. For many programs, this will be adequate; however, you may need to return to some other point in PFN's main loop. If you modified, deleted, or added files or changed the current prefix, you'll want to jump back to the point where it reads the current directory. If you didn't do anything at all to either the directory or the screen, you may just want it to jump back to the point where PFN waits for a command. In either case, you will need to pop the return address off the stack and JMP to the point you want (you do that using PFN's jump table, which I will get to later).

Programs in BIN files will have to check to see if they're running under PFN before they attempt to use any of its routines. This may be done by checking for a JMP $4100 at $4000, PFN's version number at $40FF (any value below $30, for version 3.0, means you're not running under PFN), and a JMP $1800 at $40F9. NCF files may assume they are running under PFN with no checks whatsoever, since nothing else can run NCF files.

Your program may just be a subroutine that does something and returns, such as the File.Type.Table included with PFN. It may also install a routine high up in memory, and modify PFN to assign it a letter on the keyboard or call it at some point. For simplicity's sake, I'll refer to these types of programs as "resident." If you do this, you have more restrictions on how you can use memory.


PFN's USE OF MEMORY

ProDOS File Navigator uses many different areas of memory for many different purposes. You will need to be aware of how it uses memory.

$0000 to $07FF is generally off-limits no matter what program you're running under. PFN doesn't use $300-$3CF for anything, however, so you may stick a short routine there or use it for variable storage.

$0800 to $0BFF, the second text page, is used by PFN as a buffer for loading standard and double lo-res graphics files. If your program is not resident, you may use this space however you want; otherwise, you'll need to be aware that this space will be erased whenever the user views lo-res graphics files.

$0C00 to $0CFF holds the current prefix. If this is changed, the current prefix changes, and vice versa.

$0D00 to $0DFF is the File Clipboard. It holds the path of the source file for a copy operation in $0D00-$0DDF, and a copy of the source file's catalog entry in $0DE0-$0DFF. Also, the SYS file loader will copy the SYS file's path to this location before it reads it and transfers control.

$0E00 to $0EFF is called the Catalog Extension. Each file in the file list is given 4 bytes in this area. Currently, all this is used for is to hold the file's length in bytes. Since only 54 files can be listed, only $0E00-$0ED7 is used; PFN may use the rest of the space in the future, however.

$0F00 to $0FFF is currently unused, but may be used in a future version of PFN.

$1000 to $13FF is used as the main I/O buffer when reading or writing directories and files. If your routine reads or writes files, you will want to use this area as your I/O buffer. $1400 to $17FF is used as a secondary I/O buffer, when PFN writes out a copy of a file or when it protects the double hi-res space by writing a file to /RAM. If your routine must open a second file, use this area.

$1800 to $18FF is a short routine called the SYS file loader. What this routine will do is copy the SYS file's path from $6F00 to $0D00, unprotect all of the memory areas used by PFN, load the SYS file starting at $2000, reset the stack, and jump to $2000. If the load fails, the memory areas used by PFN will be protected again, the stack will be reset, and the routine will jump to $4000, where PFN starts. This area of memory is protected in the ProDOS system bitmap; ProDOS will refuse to load anything in this area. THIS SPACE SHOULD NOT BE TOUCHED FOR ANY REASON.

$1900 to $1F00 is part of the data buffer for viewing text files. Follow the same guidelines for using this part of memory as for using the second text page.

$2000 to $3F00 is the data buffer for hi-res graphics, the rest of the data buffer for text files, and a general data buffer for copying files, reading directories, loading SYS files, and any other operations involving reading and writing files. If your program is not resident, you may use this space. Otherwise, be careful; this space will frequently be overwritten, and you should not put anything here while it is being used.

$4000 to $5FFF is the ProDOS File Navigator program itself. $4000-$40FF is a jump table that your program may use to call PFN's routines. It is not recommended to call routines in PFN directly, since they may change locations in future versions. This area of memory is protected in the ProDOS system bitmap; ProDOS will refuse to load anything in this area.

$6000 to $67FF is PFN's data and string tables. This includes all the pieces of text PFN prints, PFN's table of ProDOS file type mnemonics, and some other tables. More information on this section comes later. This area of memory is protected in the ProDOS system bitmap; ProDOS will refuse to load anything in this area.

$6800 to $6EFF is the main file catalog. Each file in the file list is given 32 bytes. The first 16 bytes of each catalog entry is the file's name; this is followed by the access code, file type, auxiliary type, storage type, block count, modification date and time, creation date and time, and one unused byte. Since only 54 files can be listed, only $6800-$6EBF is used; the remaining space may be used in a future version. This area of memory is protected in the ProDOS system bitmap; ProDOS will refuse to load anything in this area.

$6F00 to $6FFF is a general temporary string storage area. It will be overwritten and used very frequently. It is not recommended to use this area for anything, unless you're calling PFN's own routines. This area of memory is protected in the ProDOS system bitmap; ProDOS will refuse to load anything in this area.

Finally, all the memory space $7000 and above is completely unused by ProDOS File Navigator and may be used for whatever you want, with no restrictions whatsoever.

In general, PFN doesn't leave any locations in the zero page free for your use. $08 holds the number of the currently selected file, $09 holds the number of the current command line, $19-$1E holds the number of blocks available, used, and total, and $D7 holds the number of files. The other locations unused by ProDOS, BASIC, and the system monitor ($06, $07, $CE, $CF, $E3, $EB-$EF, and $FA-$FF) are used by various routines inside PFN. You may use the zero page locations used solely by Applesoft BASIC, since PFN doesn't call any routines in BASIC.

